swagger: '2.0'
info:
  title: Star Battle Odyssey API
  description: API for managing users and puzzles
  version: 1.0.5
  contact:
    name: Starbo API Support
    url: 'https://www.starbo.com/support'
    email: support@starbo.com
host: 'localhost:1391'
basePath: /
schemes:
  - http
tags: 
  - name: users
  - name: puzzles (users)
  - name: puzzles (levels)
  - name: leaderboards
paths:
  '/users/{username}':
    parameters:
      - name: username
        in: path
        required: true
        type: string
    get:
      description: Used to get a particular user
      operationId: getUserByName
      summary: Get an existing user
      security:
        - WebbAuth: []
      tags:
        - users
      produces:
        - application/json
      responses:
        '200':
          description: User object returned
          schema:
            $ref: '#/definitions/User'
        '404':
          description: User not found
    put:
      description: Used to update the user
      operationId: updateUser
      summary: Update an existing user
      security:
        - WebbAuth: []
      tags:
        - users
      produces:
        - application/json
      parameters:
        - name: username
          in: path
          required: true
          type: string
        - name: user
          in: body
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        '204':
          description: User object updated
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should
            either be the username of requested user or "admin."
        '404':
          description: User not found
    delete:
      description: Used to delete a particular user
      operationId: deleteUser
      summary: Delete an existing user
      security:
        - WebbAuth: []
      tags:
        - users
      produces:
        - application/json
      parameters:
        - name: username
          in: path
          required: true
          type: string
      responses:
        '204':
          description: User deleted
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should
            either be the username of requested user or "admin."
        '404':
          description: User not found
  /users:
    post:
      summary: Create a new user
      operationId: createUserByName
      description: Used to create a new user
      tags:
        - users
      produces:
        - application/json
      parameters:
        - name: user
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateUser'
      responses:
        '201':
          description: User object created
          schema:
            $ref: '#/definitions/User'
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should be
            "admin".
        '409':
          description: User already exists
  /leaderboards/users:
    get:
      summary: Get the leaderboard of users
      operationId: getUserLeadboard
      tags:
        - leaderboards
      description: >-
        Used to get a list of users sorted by completed puzzles. Tie breakers
        are decided by average solve time.
      produces:
        - application/json
      responses:
        '200':
          description: List of users sorted by completed puzzles
          schema:
            $ref: '#/definitions/UserLeaderBoard'
  /puzzles/levels:
    get:
      tags:
        - puzzles (levels)
      summary: Get all puzzle levels
      security:
        - WebbAuth: []
      operationId: getAllPuzzleLevels
      description: Returns a list of all puzzles
      responses:
        '200':
          description: A list of puzzles
          schema:
            type: array
            items:
              $ref: '#/definitions/PuzzleLevel'
    post:
      tags:
        - puzzles (levels)
      summary: Create a new puzzle level
      operationId: createPuzzleLevel
      security:
        - WebbAuth: []
      description: Returns the created puzzle
      parameters:
        - name: puzzle
          in: body
          description: Puzzle level data
          required: true
          schema:
            $ref: '#/definitions/CreatePuzzleLevel'
      responses:
        '201':
          description: Puzzle level created
          schema:
            type: object
            properties:
              levelId:
                type: string
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should be
            "admin".
  '/puzzles/levels/{levelId}':
    get:
      tags:
        - puzzles (levels)
      summary: Get a particular puzzle level
      security:
        - WebbAuth: []
      operationId: getPuzzleLevelById
      description: >-
        Returns a puzzle solution and aggregate statistics for the specified
        puzzle ID.
      parameters:
        - name: levelId
          in: path
          description: ID of the puzzle to retrieve
          required: true
          type: integer
      responses:
        '200':
          description: A puzzle object
          schema:
            $ref: '#/definitions/PuzzleLevel'
        '404':
          description: Puzzle not found
    put:
      tags:
        - puzzles (levels)
      summary: Used to update a puzzle level
      operationId: updatePuzzleLevelById
      security:
        - WebbAuth: []
      description: This is helpful in updating the solvedByNumPlayers or fixing errors
      parameters:
        - name: levelId
          in: path
          description: ID of the puzzle to update
          required: true
          type: integer
        - name: puzzle
          in: body
          required: true
          schema:
            $ref: '#/definitions/UpdatePuzzleLevel'
      responses:
        '204':
          description: PuzzleLevel object updated
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should be
            "admin".
        '404':
          description: PuzzleLevel not found
    delete:
      security:
        - WebbAuth: []
      tags:
        - puzzles (levels)
      summary: Used to delete a puzzle level
      operationId: deletePuzzleLevelById
      description: Delete's a puzzle by a level id
      parameters:
        - name: levelId
          in: path
          description: ID of the puzzle to delete
          required: true
          type: integer
      responses:
        '204':
          description: PuzzleLevel object deleted
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should be
            "admin".
        '404':
          description: PuzzleLevel not found
  /puzzles/users:
    post:
      tags:
        - puzzles (users)
      summary: Used to create a new user puzzle
      operationId: createUserPuzzle
      description: >-
        Given a valid level id and username, it will create a entry to store
        user stats specific to that puzzle
      security:
        - WebbAuth: []
      parameters:
        - name: user/level
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateUserPuzzle'
      responses:
        '201':
          description: Puzzle level created successfully
          schema:
            $ref: '#/definitions/UserPuzzle'
        '401':
          description: Not authorized
        '403':
          description: Permission denied
        '409':
          description: Puzzle level with the same ID already exists
  '/puzzles/users/{username}':
    get:
      tags:
        - puzzles (users)
      summary: Used to retrieve all puzzle data from a particular user
      operationId: getUserPuzzlesByUsername
      security:
        - WebbAuth: []
      description: Retrieves all puzzle data from said username
      parameters:
        - name: username
          in: path
          description: User's name
          required: true
          type: string
      responses:
        '200':
          description: UserPuzzle object
          schema:
            type: array
            items:
              $ref: '#/definitions/UserPuzzle'
        '404':
          description: Not found because the user doesn't exist.
  '/puzzles/users/{username}/{levelId}':
    get:
      tags:
        - puzzles (users)
      summary: Used to retrieve level data for a particular user
      operationId: getUserPuzzleByLevelIdAndUsername
      security:
        - WebbAuth: []
      description: >-
        This only contains data that is produced by the user. Level data is held
        as an id, a request would need to be made if the client doesn't have
        that information.
      parameters:
        - name: levelId
          in: path
          description: ID of the level puzzle
          required: true
          type: integer
        - name: username
          in: path
          description: User's name
          required: true
          type: string
      responses:
        '200':
          description: UserPuzzle object
          schema:
            $ref: '#/definitions/UserPuzzle'
        '404':
          description: Not found. Either can be do to a puzzle id or username not valid.
    put:
      tags:
        - puzzles (users)
      summary: Used to update level data for a particular user
      operationId: updateUserPuzzleByLevelIdAndUsername
      description: Only the admin or the user who owns that data can change their data
      security:
        - WebbAuth: []
      parameters:
        - name: levelId
          in: path
          description: ID of the level puzzle
          required: true
          type: integer
        - name: username
          in: path
          description: User's name
          required: true
          type: string
        - name: UserPuzzle
          in: body
          description: 'UserPuzzle data, things associated with the user'
          schema:
            $ref: '#/definitions/UpdateUserPuzzle'
      responses:
        '204':
          description: User puzzle level object updated
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should
            either be the username of requested user or "admin."
        '404':
          description: Not found
    delete:
      tags:
        - puzzles (users)
      summary: Delete a puzzle level
      operationId: deleteUserPuzzleById
      description: Only the admin or the user can delete this information
      security:
        - WebbAuth: []
      parameters:
        - name: levelId
          in: path
          description: ID of the puzzle level to delete
          required: true
          type: integer
        - name: username
          in: path
          description: The user's name
          required: true
          type: string
      responses:
        '204':
          description: Puzzle level object deleted
        '401':
          description: Not authorized.
        '403':
          description: >-
            Permission denied. Note for the authentication header, it should be
            "admin."
        '404':
          description: Not found
definitions:
  UserLeaderBoard:
    type: object
    properties:
      data:
        type: array
        items:
          type: object
          properties:
            username:
              type: string
            completedPuzzles:
              type: integer
  User:
    type: object
    properties:
      username:
        type: string
      stats:
        type: object
        properties:
          minSolveTime:
            type: number
          avgSolveTime:
            type: number
          maxSolveTime:
            type: number
          sumSolveTime:
            type: integer
          puzzlesComplete:
            type: integer
          puzzlesUntilNextTitle:
            type: integer
          currentTitle:
            type: string
  CreateUser:
    type: object
    properties:
      username:
        type: string
  PuzzleLevel:
    type: object
    properties:
      levelId:
        type: integer
      gridSize:
        type: integer
      numStars:
        type: integer
      regions:
        type: array
        items:
          type: array
          items:
            type: array
            items:
              type: integer
      solution:
        type: array
        items:
          type: array
          items:
            type: integer
      solvedByNumPlayers:
        type: number
  CreatePuzzleLevel:
    type: object
    properties:
      gridSize:
        type: integer
      numStars:
        type: integer
      regions:
        type: array
        items:
          type: array
          items:
            type: array
            items:
              type: integer
      solution:
        type: array
        items:
          type: array
          items:
            type: integer
  UpdatePuzzleLevel:
    type: object
    properties:
      gridSize:
        type: integer
      numStars:
        type: integer
      regions:
        type: array
        items:
          type: array
          items:
            type: array
            items:
              type: integer
      solution:
        type: array
        items:
          type: array
          items:
            type: integer
      solvedByNumPlayers:
        type: number
  CreateUserPuzzle:
    type: object
    properties:
      levelId:
        type: integer
      username:
        type: string
  UserPuzzle:
    type: object
    properties:
      id:
        type: string
      levelId:
        type: integer
      username:
        type: string
      completed:
        type: boolean
      solveTime:
        type: number
      placedMarkers:
        type: array
        items:
          type: array
          items:
            type: integer
      placedStars:
        type: array
        items:
          type: array
          items:
            type: integer
      starsRemaining:
        type: integer
  UpdateUserPuzzle:
    type: object
    properties:
      completed:
        type: boolean
      solveTime:
        type: number
      placedMarkers:
        type: array
        items:
          type: array
          items:
            type: integer
      placedStars:
        type: array
        items:
          type: array
          items:
            type: integer
      starsRemaining:
        type: integer
securityDefinitions:
  WebbAuth:
    type: apiKey
    in: header
    name: Authorization